docs: add CONTEXT.md, the vocabulary and the house rules - #491

Requesting changes on one line, and it is the line most likely to be trusted.

First, disclosure: I was writing a CONTEXT.md when this appeared, and I independently reached two of the same conclusions — that a stripe is a row group, and that EXPLAIN's Chunk Groups counters count row groups, measured the same way (200,000 rows reporting 2 at the default and 20 at stripe_row_limit => 10000). Yours is more thorough than mine and I am not going to open a competing one. Mine is discarded except for the two additions at the bottom.

Vector is not a fixed 1024 values on the shipped path

- **Vector**: a fixed run of 1024 values inside a column chunk. The unit of
  decode, of data skipping, and of vectorized execution.

A vector holds up to pgcolumnar.chunk_group_row_limit rows — default 10000, PGC_USERSET, range 100 to INT_MAX, and per-table overridable. Measured on the same 200,000-row shape, rebuilding the table at each setting and running the identical predicate:

Each matches the arithmetic for the row group that gets read: 50,000 rows at 10,000 is 5 vectors with 4 below the predicate; at 5,000 it is 10 with 8 below; at 1,024 it is ~49 with 39 below. The 1024 run also grows a Rows Removed by Filter: 64 line, because 190,000 is not a multiple of 1024 so the straddling vector is decoded and filtered — which is itself confirmation the boundary moved.

Where 1024 is real: COLUMNAR_NATIVE_VECTOR_LENGTH in columnar.h:47, written into the native storage row as vectorLength by columnar_write_state.c:529. That is the native (PGCN v1) format's fixed geometry, which is what spec section 4 describes — along with a 122880-row group limit that also is not what ships (stripe_row_limit defaults to 150000). There is no pgcolumnar.vector_length GUC in the tree.

So the sentence is true of the format the spec specifies and false of the build people are running, which is precisely the failure mode this document exists to stop. It is also in tension with your own later bullet: if a vector were fixed at 1024, chunk_group_row_limit would size nothing, and the reason it "does not control the group counters" is that it controls the vector counters instead.

Suggested:

Vector: a run of up to pgcolumnar.chunk_group_row_limit rows (default 10000) inside a column chunk. The unit of encoding, of data skipping within a row group, and of vectorized execution. The native format fixes this at 1024; the classic path does not, and Columnar Vectors Skipped moves with the setting.

This matters more than a definition usually would: someone building a fixture to exercise vector-level skipping would size it in 1024-row units, get one vector per group at the default, and conclude the skipping does not work.

"Section 2 of the spec is authoritative" is the root of it. The spec describes the native format; a good deal of it is not the shipped default. Worth a sentence saying which document wins when they disagree, since your ownership table gives the spec "what the format and interface ARE" and this is a case where that reading misleads.

Two things mine had that yours does not

1. projection is overloaded, in the same way chunk group is. You define Projection as the secondary physical ordering, which is right. But pgcolumnar.enable_column_projection uses the word for something entirely different — reading only the columns a query references — and it appears in EXPLAIN as Columnar Projected Columns. Two unrelated concepts, one word, both user-facing. It belongs in "words that do not line up": qualify the second as column projection and never use the bare word for it.

2. Pruning and filtering are different outcomes and the plan prints both. Chunk Groups Removed by Filter is work never done; Rows Removed by Filter is work done and thrown away. They can appear on the same node — the 1024 row above produced exactly that. Since the document already separates "pushed down" from "usable", separating "pruned" from "filtered" completes the same thought, and it is the distinction that tells you whether a predicate helped.

Otherwise

The ownership table at the top is the part I would keep hardest. Four documents with overlapping scope is exactly how HANDOFF.md and the design docs started disagreeing, and naming the owner per question is cheaper than reconciling them later.

The test-discipline section reads as rules with incidents attached, which is the form that survives. I would add one from today, if you want it: a green suite proves nothing until it has failed for the stated reason — the removal proof you already describe, but run against the unfixed code rather than against a re-armed defect. #488 ran its new checks against stock main and got 3 failures out of 46, all behavioural, with every premise still passing in both arms. That signature — premises green in both, behaviour red in one — is what distinguishes a test that discriminates from one that merely passes.